home *** CD-ROM | disk | FTP | other *** search
/ Libris Britannia 4 / science library(b).zip / science library(b) / MATH / FSULTRA1.ZIP / README < prev    next >
Text File  |  1992-06-18  |  7KB  |  208 lines
  1. FSU - ULTRA    The greatest random number generator that ever was
  2.         or ever will be.  Way beyond Super-Duper.
  3.         (Just kidding, but we think its a good one.)
  4.  
  5. Authors:    Arif Zaman (arif@stat.fsu.edu) and
  6.         George Marsaglia (geo@stat.fsu.edu).
  7.  
  8. Date:        27 May 1992
  9.  
  10. Version:    1.05
  11.  
  12. Copyright:    To obtain permission to incorporate this program into
  13.         any commercial product, please contact the authors at
  14.         the e-mail address given above or at
  15.  
  16.         Department of Statistics and
  17.         Supercomputer Computations Research Institute
  18.         Florida State University
  19.         Tallahassee, FL 32306.
  20.  
  21. See Also:    README        for a brief description
  22.         ULTRA.DOC    for a detailed description
  23.  
  24. -----------------------------------------------------------------------
  25.             SUMMARY OF CONTENTS
  26.  
  27. Every file in this distribution is described in this file.
  28.  
  29. THE MAIN CODE
  30. -------------
  31.  
  32.   The assembly code (using TASM 2.0) for the random number generator
  33.   is contained in the files:
  34.  
  35.     ULTRACOD.INC
  36.     ULTRADAT.INC
  37.  
  38.   An interface file, which includes these files and defines a particular
  39.   language interface, must be written for each language. The files
  40.  
  41.     ULTRA_C.ASM    - Turbo C++ 1.0
  42.     ULTRA_TP.ASM     - Turbo Pascal 6.0
  43.     ULTRA_LH.ASM    - Lahey Fortran
  44.     ULTRA_FR.ASM    - IBM Fortran/2
  45.  
  46.   define the interfaces for the abovementioned languages. It is easy to
  47.   write other interfaces, given a description of the calling sequence
  48.   for the language.
  49.  
  50. THE C IMPLEMENTATION
  51. --------------------
  52.  
  53.     ULTRA.C
  54.     ULTRA.H
  55.  
  56.   is a C implementation of the same algorithm, which is about half
  57.   as fast as the assembler version. Those who wish to port it to
  58.   other architectures may wish to use it as a starting point.
  59.   We would like to hear of any successful ports.
  60.  
  61.     ULTRAMAC.C
  62.  
  63.   is the same as ULTRA.C, but uses macros rather than function calls
  64.   to implement many of the random number procedures. This makes it a
  65.   bit faster. On the other hand occaisionally, macros behave slightly
  66.   differently from functions, so use it carefully.
  67.  
  68. THE "FAST" VERSION
  69. ------------------
  70.  
  71.   If the variable "fast" is defined (via the -dfast switch for TASM, or
  72.   -Dfast for Turbo C), the above programs will skip one step (the mixing
  73.   with a congruential generator) in the algorithm to produce a faster
  74.   version of the same routines, which produces an inferior quality of
  75.   random numbers. This is not recommended for mathematical work.
  76.  
  77. THE "X" version
  78. ---------------
  79.  
  80.   For those fortunate ones with 80386 or 80486 machines, some speed gains
  81.   are possible by using the 32bit capabilities of these CPU's. A whole
  82.   set of new programs:
  83.  
  84.     ULTRXCOD.INC
  85.     ULTRX_C.ASM
  86.     ULTRX_TP.ASM
  87.     ULTRX_LH.ASM
  88.     ULTRX_FR.ASM
  89.  
  90.   implement this version.
  91.  
  92. OBJECT FILES
  93. ------------
  94.  
  95.   For those without access to TASM, compiled version of the routines are
  96.   provided in a subdirectory. The names of the .OBJ files are coded
  97.   using the following scheme:
  98.  
  99.     All .OBJ file names begin with "ULT_", followed by a two letter code
  100.     for the language:
  101.     CT, CS, CM, CC, CL CH : for Turbo C (tiny, small, medium, compact,
  102.                 large and huge) memory models.
  103.     TP    - Turbo Pascal
  104.     LH    - Lahey Fortran
  105.     FR    - IBM Fortran/2
  106.     An additional suffix of  F  denotes the fast version
  107.     An additional suffix of  X  denotes the 80386/80486 version
  108.  
  109.   Thus ULT_CMFX.OBJ is the Turbo C medium model Fast 80386/80486 version.
  110.  
  111.   For convenience for Turbo Pascal users the TPU files (version 6.0)
  112.  
  113.     ULTRA.TPU    ULTRAF.TPU
  114.     ULTRAX.TPU    ULTRAFX.TPU
  115.  
  116.   have been included. To make some TPU's for a different version of Turbo
  117.   Pascal, use the file
  118.  
  119.     ULTRATPU.PAS
  120.  
  121. DEMO/TEST
  122. ---------
  123.  
  124.   A program to demonstrate the use as well as to serve for a benchmark
  125.   test was written in all the languages which have been implemented.
  126.   The programs are:
  127.  
  128.     DEMO.C
  129.     DEMO.TP
  130.     DEMO.FOR
  131.  
  132.   All the languages gave identical output (except Turbo C, tiny model
  133.   which seems to use some different rounding for printouts and hence
  134.   differs in the floating point numbers. Using Turbo Debugger it was
  135.   verified that the numbers being generated are identical, but the
  136.   printf routine prints them differently!).
  137.  
  138.   IBM Fortran/2 seems to crash and/or behave unpredictably with the
  139.   "X" versions of ULTRA. For this reason, they were excluded from the
  140.   compiled programs. I don't know why this happens. The assembler files
  141.   are included for those who wish to explore this.
  142.  
  143. TIMINGS
  144. -------
  145.  
  146.   A file called
  147.  
  148.     TIMINGS.C
  149.  
  150.   is included for those who wish to see how fast is fast. This is
  151.   written using the Zen Timer library (ZTIMER11.ZIP) which provides
  152.   microsecond timing accuracy on the PC's. The library is not included
  153.   but is available for remote ftp from SIMTEL or any of its mirrors,
  154.   e.g. (wuarchive.wustl.edu in /mirrors/msdos/c/ztimer11.zip)
  155.  
  156.  
  157. MAKEFILE
  158. --------
  159.  
  160.   Using the make utility, it is easy to excercise the various parts
  161.   of this package. The `make' program is usually supplied with all
  162.   Borland products, but public domain versions exist and can be found
  163.   on SIMTEL as well. Here is a list of what make can do:
  164.  
  165.   Command    Effect
  166.   -------    ------
  167.   make        will remake all the .obj files
  168.   make c    will make all the Turbo C .obj files
  169.   make tp    will make all the Turbo Pascal .tpu files. You
  170.         need to do this if you don't have TP 6.0.
  171.   make lahey    will make all the Lahey Fortran .obj files
  172.   make fort    will make all the IBM Fortran/2 .obj files
  173.   make demo    will run all the demos
  174.   make democ    will run all the Turbo C demos
  175.   make demotp    or `make demolahey' or `make demofort'
  176.         will run demos for the other languages.
  177.         The demos will result in a file called dif.out,
  178.         which will compare the different versions to see
  179.         if they produce the same output.
  180.   make clean    will remove all the junk created.
  181.  
  182.   You may need to edit the file called
  183.  
  184.     MAKEFILE
  185.  
  186.   to reflect the paths of the various compilers on your machine
  187.  
  188. BUGS:
  189. -----
  190.  
  191.   There seem to be problems using 32bit code with IBM Fortran/2 and
  192.   with the Turbo-C Tiny model. 
  193.  
  194.   The Tubro-C bugs persist even with "TCC -MT DEMO.C ULTRA.C" where
  195.   there is no assembler code. When I run it in the integrated enviroment,
  196.   or in Turbo Debugger, it runs flawlessly. I am baffled.
  197.  
  198.  
  199. CHANGES: (from ULTRA101.ZIP)
  200. --------
  201.     Further speedup of assembler code.
  202.  
  203.     More than doubled the speed of ULTRA.C (using if's to do SWB).
  204.  
  205.     Caught serious error in vni's. Modified program so it could
  206.     be implemented on machines which worry about alignment.
  207.     This caused added space, and changed the output stream.
  208.